<!DOCTYPE html>
<html lang="en">

<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
	<meta name="keywords" content="Open API,Guide" />
	<meta name="description" content="Open API Guide" />
	<!-- 网页标签标题 -->
	<title>Open API Guide</title>
	<link rel="shortcut icon" href="https://img.alicdn.com/tfs/TB1hgJpHAPoK1RjSZKbXXX1IXXa-64-64.png"/>
	<link rel="stylesheet" href="/build/documentation.css" />
</head>
<body>
	<div id="root"><div class="documentation-page" data-reactroot=""><header class="header-container header-container-normal"><div class="header-body"><a href="/en-us/index.html"><img class="logo" src="/img/nacos_colorful.png"/></a><div class="search search-normal"><span class="icon-search"></span></div><span class="language-switch language-switch-normal">中</span><div class="header-menu"><img class="header-menu-toggle" src="/img/menu_gray.png"/><ul><li class="menu-item menu-item-normal"><a href="/en-us/index.html">HOME</a></li><li class="menu-item menu-item-normal menu-item-normal-active"><a href="/en-us/docs/quick-start.html">DOCS</a></li><li class="menu-item menu-item-normal"><a href="/en-us/blog">BLOG</a></li><li class="menu-item menu-item-normal"><a href="/en-us/community">COMMUNITY</a></li><li class="menu-item menu-item-normal"><a href="https://cn.aliyun.com/product/aliware/mse?spm=nacos-website.topbar.0.0.0">NACOS IN CLOUD</a><img class="menu-img" src="https://img.alicdn.com/tfs/TB1esl_m.T1gK0jSZFrXXcNCXXa-200-200.png"/></li><li class="menu-item menu-item-normal"><a href="http://console.nacos.io/nacos/index.html">DEMO-CONSOLE</a></li></ul></div></div></header><div class="bar"><div class="bar-body"><img src="/img/docs.png" class="front-img"/><div class="bar-title"><span>Documentation</span><div class="bone bone-light"></div></div><img src="/img/docs.png" class="back-img"/></div></div><section class="content-section"><div class="content-body"><div class="sidemenu"><div class="sidemenu-toggle"><img src="https://img.alicdn.com/tfs/TB1E6apXHGYBuNjy0FoXXciBFXa-200-200.png"/></div><ul><li class="menu-item menu-item-level-1"><span>Nacos </span><ul><li style="height:180px;overflow:hidden" class="menu-item menu-item-level-2"><span>What is Nacos<img style="transform:rotate(0deg)" class="menu-toggle" src="/img/arrow_down.png"/></span><ul><li class="menu-item menu-item-level-3"><a href="/en-us/docs/what-is-nacos.html" target="_self">What is Nacos</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/concepts.html" target="_self">Concepts</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/architecture.html" target="_self">Architecure</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/feature-list.html" target="_self">Feature list</a></li></ul></li><li style="height:324px;overflow:hidden" class="menu-item menu-item-level-2"><span>Quick Start<img style="transform:rotate(0deg)" class="menu-toggle" src="/img/arrow_down.png"/></span><ul><li class="menu-item menu-item-level-3"><a href="/en-us/docs/quick-start.html" target="_self">Nacos</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/quick-start-spring.html" target="_self">Nacos Spring</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/quick-start-spring-boot.html" target="_self">Nacos Spring Boot</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/quick-start-spring-cloud.html" target="_self">Nacos Spring Cloud</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/quick-start-docker.html" target="_self">Nacos Docker</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/use-nacos-with-dubbo.html" target="_self">Nacos with Dubbo</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/use-nacos-with-kubernetes.html" target="_self">Nacos with K8s</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/nacos-sync.html" target="_self">Nacos Sync</a></li></ul></li><li style="height:252px;overflow:hidden" class="menu-item menu-item-level-2"><span>User Guide<img style="transform:rotate(0deg)" class="menu-toggle" src="/img/arrow_down.png"/></span><ul><li class="menu-item menu-item-level-3"><a href="/en-us/docs/sdk.html" target="_self">Java SDK</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/other-language.html" target="_self">Other Language</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/open-api.html" target="_self">Open-API</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/nacos-spring.html" target="_self">Nacos Spring</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/system-configurations.html" target="_self">Nacos System Configurations</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/faq.html" target="_self">FAQ</a></li></ul></li><li style="height:36px;overflow:hidden" class="menu-item menu-item-level-2"><span>Admin Guide<img style="transform:rotate(-90deg)" class="menu-toggle" src="/img/arrow_down.png"/></span><ul><li class="menu-item menu-item-level-3"><a href="/en-us/docs/deployment.html" target="_self">Deployment Guide</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/cluster-mode-quick-start.html" target="_self">Cluster Mode Deployment</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/management-api.html" target="_self">Management OpenAPI</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/console-guide.html" target="_self">Admin Console Guide</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/monitor-guide.html" target="_self">Nacos Monitor Guide</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/nacos-config-benchmark.html" target="_self">Nacos Config Benchmark</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/nacos-naming-benchmark.html" target="_self">Nacos Naming Benchmark</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/nacos-sync-use.html" target="_self">Data Migration to Nacos</a></li></ul></li><li style="height:36px;overflow:hidden" class="menu-item menu-item-level-2"><span>Contributor Guide<img style="transform:rotate(-90deg)" class="menu-toggle" src="/img/arrow_down.png"/></span><ul><li class="menu-item menu-item-level-3"><a href="/en-us/docs/contributing.html" target="_self">Contribute to Nacos</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/contributing-flow.html" target="_self">Contributing Flow</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/pull-request.html" target="_self">Pull Request Template</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/how-to-reporting-bugs.html" target="_self">How to report bugs</a></li></ul></li><li style="height:36px;overflow:hidden" class="menu-item menu-item-level-2"><span>Community<img style="transform:rotate(-90deg)" class="menu-toggle" src="/img/arrow_down.png"/></span><ul><li class="menu-item menu-item-level-3"><a href="/en-us/docs/community.html" target="_self">Community</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/nacos-dev.html" target="_self">Develop Team</a></li></ul></li></ul></li></ul></div><div class="doc-content markdown-body"><h1>Open API Guide</h1>
<ul>
<li>
<p>Configuration Management</p>
<ul>
<li><a href="#1.1">Get configurations</a></li>
<li><a href="#1.2">Listen for configurations</a></li>
<li><a href="#1.3">Publish configuration</a></li>
<li><a href="#1.4">Delete configuration</a></li>
</ul>
</li>
<li>
<p>Service Discovery</p>
<ul>
<li><a href="#2.1">Register instance</a></li>
<li><a href="#2.2">Deregister instance</a></li>
<li><a href="#2.3">Modify instance</a></li>
<li><a href="#2.4">Query instances</a></li>
<li><a href="#2.5">Query instance detail</a></li>
<li><a href="#2.6">Send instance beat</a></li>
<li><a href="#2.7">Create service</a></li>
<li><a href="#2.8">Delete service</a></li>
<li><a href="#2.9">Update service</a></li>
<li><a href="#2.10">Query service</a></li>
<li><a href="#2.11">Query service list</a></li>
<li><a href="#2.12">Query system switches</a></li>
<li><a href="#2.13">Update system switch</a></li>
<li><a href="#2.14">Query system metrics</a></li>
<li><a href="#2.15">Query server list</a></li>
<li><a href="#2.16">Query the leader of current cluster</a></li>
<li><a href="#2.17">Update instance health status</a></li>
<li><a href="#2.18">Batch update instance metadata(Beta)</a></li>
<li><a href="#2.19">Batch delete instance metadata(Beta)</a></li>
</ul>
</li>
</ul>
<h2>Configuration Management</h2>
<h2 id="1.1">Get configurations</h2>
<h3>Description</h3>
<p>This API is used to get configurations in Nacos.</p>
<h3>Request type</h3>
<p>GET</p>
<h3>Request URL</h3>
<p>/nacos/v1/cs/configs</p>
<h3>Request parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Name</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Required</th>
<th style="text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">tenant</td>
<td style="text-align:left">string</td>
<td style="text-align:left">No</td>
<td style="text-align:left">Tenant information. It corresponds to the Namespace ID field in Nacos.</td>
</tr>
<tr>
<td style="text-align:left">dataId</td>
<td style="text-align:left">string</td>
<td style="text-align:left">Yes</td>
<td style="text-align:left">Configuration ID</td>
</tr>
<tr>
<td style="text-align:left">group</td>
<td style="text-align:left">string</td>
<td style="text-align:left">Yes</td>
<td style="text-align:left">Configuration group</td>
</tr>
</tbody>
</table>
<h3>Return parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Parameter type</th>
<th style="text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">String</td>
<td style="text-align:left">Configuration value</td>
</tr>
</tbody>
</table>
<h3>Error codes</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Error code</th>
<th style="text-align:left">Description</th>
<th style="text-align:left">Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">400</td>
<td style="text-align:left">Bad Request</td>
<td style="text-align:left">Syntax error in the client request</td>
</tr>
<tr>
<td style="text-align:left">403</td>
<td style="text-align:left">Forbidden</td>
<td style="text-align:left">No permission</td>
</tr>
<tr>
<td style="text-align:left">404</td>
<td style="text-align:left">Not Found</td>
<td style="text-align:left">Not found resource</td>
</tr>
<tr>
<td style="text-align:left">500</td>
<td style="text-align:left">Internal Server Error</td>
<td style="text-align:left">Internal server error</td>
</tr>
<tr>
<td style="text-align:left">200</td>
<td style="text-align:left">OK</td>
<td style="text-align:left">Normal</td>
</tr>
</tbody>
</table>
<h3>Example</h3>
<ul>
<li>
<p>Request example</p>
<pre><code>http:serverIp:8848/nacos/v1/cs/configs?dataId=dataIdparam&amp;group=groupParam&amp;tenant=tenantParam

</code></pre>
</li>
<li>
<p>Return example</p>
<pre><code>contentTest
</code></pre>
</li>
</ul>
<h2 id="1.2">Listen for configurations</h2>
<h3>Description</h3>
<p>This API is used to listen for configurations in Nacos to capture configuration changes. In case of any configuration changes, you can use the <a href="~~64131~~">Get Configurations</a> API to obtain the latest value of the configuration and dynamically refresh the local cache.</p>
<p>A listener is registered using an asynchronous servlet. The nature of registering a listener is to compare the configuration value and the MD5 value of it with that of the backend. If the values differ, the inconsistent configuration is returned immediately. Otherwise, an empty string is returned after 30 seconds.</p>
<h3>Request type</h3>
<p>POST</p>
<h3>Request URL</h3>
<p>/nacos/v1/cs/configs/listener</p>
<h3>Request parameters</h3>
<div class="bi-table">
  <table>
    <colgroup>
      <col width="auto" />
      <col width="75px" />
      <col width="96px" />
      <col width="385px" />
    </colgroup>
    <tbody>
      <tr>
        <td rowspan="1" colSpan="1">
          <div data-type="p">Name</div>
        </td>
        <td rowspan="1" colSpan="1">
          <div data-type="p">Type</div>
        </td>
        <td rowspan="1" colSpan="1">
          <div data-type="p">Required</div>
        </td>
        <td rowspan="1" colSpan="1">
          <div data-type="p">Description</div>
        </td>
      </tr>
      <tr>
        <td rowspan="1" colSpan="1">
          <div data-type="p">Listening-Configs</div>
        </td>
        <td rowspan="1" colSpan="1">
          <div data-type="p">string</div>
        </td>
        <td rowspan="1" colSpan="1">
          <div data-type="p">No</div>
        </td>
        <td rowspan="1" colSpan="1">
          <div data-type="p">A request to listen for data packets. </div>
          <div data-type="p">Format : dataId^group^2contentMD5^tenant^1 or dataId^group^2contentMD5^1.</div>
          <ul data-type="unordered-list">
            <li data-type="list-item" data-list-type="unordered-list">
              <div data-type="p">dataId : Configuration ID</div>
            </li>
            <li data-type="list-item" data-list-type="unordered-list">
              <div data-type="p">group : Configuration group</div>
            </li>
            <li data-type="list-item" data-list-type="unordered-list">
              <div data-type="p">contentMD5 : The MD5 value of the configuration</div>
            </li>
            <li data-type="list-item" data-list-type="unordered-list">
              <div data-type="p">tenant : Tenant information. It corresponds to the Namespace field in Nacos (not must)</div>
            </li>
          </ul>
        </td>
      </tr>
      <tr>
        <td rowspan="1" colSpan="1">
          <div data-type="p">Listening-Configs</div>
        </td>
        <td rowspan="1" colSpan="1">
          <div data-type="p">string</div>
        </td>
        <td rowspan="1" colSpan="1">
          <div data-type="p">Yes</div>
        </td>
        <td rowspan="1" colSpan="1">
          <div data-type="p">A request to listen for data packets.</div>
        </td>
      </tr>
      <tr>
        <td rowspan="1" colSpan="1">
          <div data-type="p">tenant</div>
        </td>
        <td rowspan="1" colSpan="1">
          <div data-type="p">string</div>
        </td>
        <td rowspan="1" colSpan="1">
          <div data-type="p">Yes</div>
        </td>
        <td rowspan="1" colSpan="1">
          <div data-type="p">A packet field indicating tenant information. It corresponds to the Namespace field in Nacos.</div>
        </td>
      </tr>
      <tr>
        <td rowspan="1" colSpan="1">
          <div data-type="p">dataId</div>
        </td>
        <td rowspan="1" colSpan="1">
          <div data-type="p">string</div>
        </td>
        <td rowspan="1" colSpan="1">
          <div data-type="p">Yes</div>
        </td>
        <td rowspan="1" colSpan="1">
          <div data-type="p">A packet field indicating the configuration ID.</div>
        </td>
      </tr>
      <tr>
        <td rowspan="1" colSpan="1">
          <div data-type="p">group</div>
        </td>
        <td rowspan="1" colSpan="1">
          <div data-type="p">string</div>
        </td>
        <td rowspan="1" colSpan="1">
          <div data-type="p">Yes</div>
        </td>
        <td rowspan="1" colSpan="1">
          <div data-type="p">A packet field indicating the configuration group.</div>
        </td>
      </tr>
      <tr>
        <td rowspan="1" colSpan="1">
          <div data-type="p">contentMD5</div>
        </td>
        <td rowspan="1" colSpan="1">
          <div data-type="p">string</div>
        </td>
        <td rowspan="1" colSpan="1">
          <div data-type="p">Yes</div>
        </td>
        <td rowspan="1" colSpan="1">
          <div data-type="p">A packet field indicating the MD5 value of the configuration.</div>
        </td>
      </tr>
    </tbody>
  </table>
</div>
<h3>Header parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Name</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Required</th>
<th style="text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">Long-Pulling-Timeout</td>
<td style="text-align:left">string</td>
<td style="text-align:left">Yes</td>
<td style="text-align:left">The timeout for long polling is 30s. Enter 30,000 here.</td>
</tr>
</tbody>
</table>
<h3>Parameter description</h3>
<ul>
<li>A delimiter to separate fields within a configuration: ^2  = Character.toString((char) 2</li>
<li>A delimiter to separate configurations: ^1 = Character.toString((char) 1)</li>
<li>contentMD5:  MD5(content). This is an empty string because the first local cache is empty.</li>
</ul>
<h3>Return parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Parameter type</th>
<th style="text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">String</td>
<td style="text-align:left">Configuration value</td>
</tr>
</tbody>
</table>
<h3>Error codes</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Error code</th>
<th style="text-align:left">Description</th>
<th style="text-align:left">Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">400</td>
<td style="text-align:left">Bad Request</td>
<td style="text-align:left">Syntax error in the client request</td>
</tr>
<tr>
<td style="text-align:left">403</td>
<td style="text-align:left">Forbidden</td>
<td style="text-align:left">No permission</td>
</tr>
<tr>
<td style="text-align:left">404</td>
<td style="text-align:left">Not Found</td>
<td style="text-align:left">Client error, not found</td>
</tr>
<tr>
<td style="text-align:left">500</td>
<td style="text-align:left">Internal Server Error</td>
<td style="text-align:left">Internal server error</td>
</tr>
<tr>
<td style="text-align:left">200</td>
<td style="text-align:left">OK</td>
<td style="text-align:left">Normal</td>
</tr>
</tbody>
</table>
<h3>Example</h3>
<ul>
<li>Request example</li>
</ul>
<pre><code>http://serverIp:8848/nacos/v1/cs/configs/listener

POST request body data:

Listening-Configs=dataId^2group^2contentMD5^2tenant^1

</code></pre>
<ul>
<li>Return example</li>
</ul>
<pre><code>In case of any configuration changes,

dataId^2group^2tenant^1

Otherwise, an empty string is returned.

</code></pre>
<h2 id="1.3">Publish configuration</h2>
<h3>Description</h3>
<p>It publishes configurations in Nacos.</p>
<h3>Request Type</h3>
<p>POST</p>
<h3>Request URL</h3>
<p>/nacos/v1/cs/configs</p>
<h3>Request parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Name</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Required</th>
<th style="text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">tenant</td>
<td style="text-align:left">String</td>
<td style="text-align:left">No</td>
<td style="text-align:left">The tenant, corresponding to the namespace ID field of Nacos</td>
</tr>
<tr>
<td style="text-align:left">dataId</td>
<td style="text-align:left">String</td>
<td style="text-align:left">Yes</td>
<td style="text-align:left">Configuration ID</td>
</tr>
<tr>
<td style="text-align:left">group</td>
<td style="text-align:left">String</td>
<td style="text-align:left">Yes</td>
<td style="text-align:left">Configuration group</td>
</tr>
<tr>
<td style="text-align:left">content</td>
<td style="text-align:left">String</td>
<td style="text-align:left">Yes</td>
<td style="text-align:left">Configuration content</td>
</tr>
<tr>
<td style="text-align:left">type</td>
<td style="text-align:left">String</td>
<td style="text-align:left">No</td>
<td style="text-align:left">Configuration type</td>
</tr>
</tbody>
</table>
<h3>Response parameters</h3>
<table>
<thead>
<tr>
<th>Parametertype</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>boolean</td>
<td>If the publishing is successful</td>
</tr>
</tbody>
</table>
<h3>Error code</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Error code</th>
<th style="text-align:left">Description</th>
<th style="text-align:left">Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">400</td>
<td style="text-align:left">Bad Request</td>
<td style="text-align:left">Syntax error in client request</td>
</tr>
<tr>
<td style="text-align:left">403</td>
<td style="text-align:left">Forbidden</td>
<td style="text-align:left">No permission</td>
</tr>
<tr>
<td style="text-align:left">404</td>
<td style="text-align:left">Not Found</td>
<td style="text-align:left">Not found resource</td>
</tr>
<tr>
<td style="text-align:left">500</td>
<td style="text-align:left">Internal Server Error</td>
<td style="text-align:left">Internal server error</td>
</tr>
<tr>
<td style="text-align:left">200</td>
<td style="text-align:left">OK</td>
<td style="text-align:left">Normal</td>
</tr>
</tbody>
</table>
<h3>Example</h3>
<h3>Request example</h3>
<pre><code>http:serverIp:8848/nacos/v1/cs/configs

http body：
dataId=dataIdparam&amp;group=groupParam&amp;tenant=tenantParam&amp;content=contentParam&amp;type=typeParam

</code></pre>
<h4>Response example</h4>
<pre><code>true
</code></pre>
<h2 id="1.4">Delete configuration</h2>
<h3>Description</h3>
<p>It deletes configurations in Nacos.</p>
<h3>Request Type</h3>
<p>DELETE</p>
<h3>Request URL</h3>
<p>/nacos/v1/cs/configs</p>
<h3>Request parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Name</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Required</th>
<th style="text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">tenant</td>
<td style="text-align:left">String</td>
<td style="text-align:left">No</td>
<td style="text-align:left">The tenant, corresponding to the namespace ID field of Nacos</td>
</tr>
<tr>
<td style="text-align:left">dataId</td>
<td style="text-align:left">String</td>
<td style="text-align:left">Yes</td>
<td style="text-align:left">Configuration ID</td>
</tr>
<tr>
<td style="text-align:left">group</td>
<td style="text-align:left">String</td>
<td style="text-align:left">Yes</td>
<td style="text-align:left">Configuration group</td>
</tr>
</tbody>
</table>
<h3>Response parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Parameter type</th>
<th style="text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">boolean</td>
<td style="text-align:left">If the deletion is successful</td>
</tr>
</tbody>
</table>
<h3>Error code</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Error code</th>
<th style="text-align:left">Description</th>
<th style="text-align:left">Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">400</td>
<td style="text-align:left">Bad Request</td>
<td style="text-align:left">Syntax error in client request</td>
</tr>
<tr>
<td style="text-align:left">403</td>
<td style="text-align:left">Forbidden</td>
<td style="text-align:left">No permission</td>
</tr>
<tr>
<td style="text-align:left">404</td>
<td style="text-align:left">Not Found</td>
<td style="text-align:left">Not found resource</td>
</tr>
<tr>
<td style="text-align:left">500</td>
<td style="text-align:left">Internal Server Error</td>
<td style="text-align:left">Internal server error</td>
</tr>
<tr>
<td style="text-align:left">200</td>
<td style="text-align:left">OK</td>
<td style="text-align:left">Normal</td>
</tr>
</tbody>
</table>
<h3>Example</h3>
<h4>Request example</h4>
<pre><code>http:serverIp:8848/nacos/cs/configs?dataId=dataIdparam&amp;group=groupParam

</code></pre>
<h4>Response example</h4>
<pre><code>true
</code></pre>
<h2>Service Discovery</h2>
<h2 id="2.1">Register instance</h2>
<h3>Description</h3>
<p>Register an instance to service.</p>
<h3>Request Type</h3>
<p>POST</p>
<h3>Request Path</h3>
<pre><code class="language-plain">/nacos/v1/ns/instance
</code></pre>
<h3>Request Parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Name</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">ip</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>IP of instance</td>
</tr>
<tr>
<td style="text-align:left">port</td>
<td style="text-align:left">int</td>
<td style="text-align:left">yes</td>
<td>Port of instance</td>
</tr>
<tr>
<td style="text-align:left">namespaceId</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>ID of namespace</td>
</tr>
<tr>
<td style="text-align:left">weight</td>
<td style="text-align:left">double</td>
<td style="text-align:left">no</td>
<td>Weight</td>
</tr>
<tr>
<td style="text-align:left">enabled</td>
<td style="text-align:left">boolean</td>
<td style="text-align:left">no</td>
<td>enabled or not</td>
</tr>
<tr>
<td style="text-align:left">healthy</td>
<td style="text-align:left">boolean</td>
<td style="text-align:left">no</td>
<td>healthy or not</td>
</tr>
<tr>
<td style="text-align:left">metadata</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>extended information</td>
</tr>
<tr>
<td style="text-align:left">clusterName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>cluster name</td>
</tr>
<tr>
<td style="text-align:left">serviceName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>service name</td>
</tr>
<tr>
<td style="text-align:left">groupName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>group name</td>
</tr>
<tr>
<td style="text-align:left">ephemeral</td>
<td style="text-align:left">boolean</td>
<td style="text-align:left">no</td>
<td>if instance is ephemeral</td>
</tr>
</tbody>
</table>
<h3>Request Example</h3>
<pre><code class="language-plain">curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/instance?port=8848&amp;healthy=true&amp;ip=11.11.11.11&amp;weight=1.0&amp;serviceName=nacos.test.3&amp;encoding=GBK&amp;namespaceId=n1''
</code></pre>
<h3>Response Example</h3>
<p>ok</p>
<h2 id="2.2">Deregister instance</h2>
<h3>Description</h3>
<p>Delete instance from service.</p>
<h3>Request Type</h3>
<p>DELETE</p>
<h3>Request Path</h3>
<pre><code class="language-plain">/nacos/v1/ns/instance
</code></pre>
<h3>Request Parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Name</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">serviceName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>Service name</td>
</tr>
<tr>
<td style="text-align:left">groupName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>group name</td>
</tr>
<tr>
<td style="text-align:left">ephemeral</td>
<td style="text-align:left">boolean</td>
<td style="text-align:left">no</td>
<td>if instance is ephemeral</td>
</tr>
<tr>
<td style="text-align:left">ip</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>IP of instance</td>
</tr>
<tr>
<td style="text-align:left">port</td>
<td style="text-align:left">int</td>
<td style="text-align:left">yes</td>
<td>Port of instance</td>
</tr>
<tr>
<td style="text-align:left">clusterName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>Cluster name</td>
</tr>
<tr>
<td style="text-align:left">namespaceId</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>ID of namespace</td>
</tr>
</tbody>
</table>
<h3>Request Example</h3>
<pre><code class="language-plain">curl -X DELETE 127.0.0.1:8848/nacos/v1/ns/instance?serviceName=nacos.test.1&amp;ip=1.1.1.1&amp;port=8888&amp;clusterName=TEST1
</code></pre>
<h3>Response Example</h3>
<p>ok</p>
<h2 id="2.3">Modify instance</h2>
<h3>Description</h3>
<p>Modify an instance of service.</p>
<h3>Request Type</h3>
<p>PUT</p>
<h3>Request Path</h3>
<pre><code class="language-plain">/nacos/v1/ns/instance
</code></pre>
<h3>Request Parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Name</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">serviceName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>Service name</td>
</tr>
<tr>
<td style="text-align:left">groupName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>group name</td>
</tr>
<tr>
<td style="text-align:left">ephemeral</td>
<td style="text-align:left">boolean</td>
<td style="text-align:left">no</td>
<td>if instance is ephemeral</td>
</tr>
<tr>
<td style="text-align:left">ip</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>IP of instance</td>
</tr>
<tr>
<td style="text-align:left">port</td>
<td style="text-align:left">int</td>
<td style="text-align:left">yes</td>
<td>Port of instance</td>
</tr>
<tr>
<td style="text-align:left">clusterName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>Cluster name</td>
</tr>
<tr>
<td style="text-align:left">namespaceId</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>ID of namespace</td>
</tr>
<tr>
<td style="text-align:left">weight</td>
<td style="text-align:left">double</td>
<td style="text-align:left">no</td>
<td>Weight</td>
</tr>
<tr>
<td style="text-align:left">enabled</td>
<td style="text-align:left">boolean</td>
<td style="text-align:left">no</td>
<td>If enabled</td>
</tr>
<tr>
<td style="text-align:left">metadata</td>
<td style="text-align:left">JSON</td>
<td style="text-align:left">no</td>
<td>Extended information</td>
</tr>
</tbody>
</table>
<h3>Request Example</h3>
<pre><code class="language-plain">curl -X PUT 127.0.0.1:8848/nacos/v1/ns/instance?serviceName=nacos.test.1&amp;ip=1.1.1.1&amp;port=8888&amp;clusterName=TEST1&amp;weight=8&amp;metadata={}
</code></pre>
<h3>Response Example</h3>
<p>ok</p>
<h2 id="2.4">Query instances</h2>
<h3>Description</h3>
<p>Query instance list of service.</p>
<h3>Request Type</h3>
<p>GET</p>
<h3>Request Path</h3>
<pre><code class="language-plain">/nacos/v1/ns/instance/list
</code></pre>
<h3>Request Parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Name</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">serviceName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>Service name</td>
</tr>
<tr>
<td style="text-align:left">groupName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>group name</td>
</tr>
<tr>
<td style="text-align:left">namespaceId</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>ID of namespace</td>
</tr>
<tr>
<td style="text-align:left">clusters</td>
<td style="text-align:left">String, splited by comma</td>
<td style="text-align:left">no</td>
<td>Cluster name</td>
</tr>
<tr>
<td style="text-align:left">healthyOnly</td>
<td style="text-align:left">boolean</td>
<td style="text-align:left">no, default value is false</td>
<td>Return healthy instance or not</td>
</tr>
</tbody>
</table>
<h3>Request Example</h3>
<pre><code class="language-plain">curl -X GET 127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=nacos.test.1
</code></pre>
<h3>Response Example</h3>
<pre><code class="language-json">{
	<span class="hljs-attr">"dom"</span>: <span class="hljs-string">"nacos.test.1"</span>,
	<span class="hljs-attr">"cacheMillis"</span>: <span class="hljs-number">1000</span>,
	<span class="hljs-attr">"useSpecifiedURL"</span>: <span class="hljs-literal">false</span>,
	<span class="hljs-attr">"hosts"</span>: [{
		<span class="hljs-attr">"valid"</span>: <span class="hljs-literal">true</span>,
		<span class="hljs-attr">"marked"</span>: <span class="hljs-literal">false</span>,
		<span class="hljs-attr">"instanceId"</span>: <span class="hljs-string">"10.10.10.10-8888-DEFAULT-nacos.test.1"</span>,
		<span class="hljs-attr">"port"</span>: <span class="hljs-number">8888</span>,
		<span class="hljs-attr">"ip"</span>: <span class="hljs-string">"10.10.10.10"</span>,
		<span class="hljs-attr">"weight"</span>: <span class="hljs-number">1.0</span>,
		<span class="hljs-attr">"metadata"</span>: {}
	}],
	<span class="hljs-attr">"checksum"</span>: <span class="hljs-string">"3bbcf6dd1175203a8afdade0e77a27cd1528787794594"</span>,
	<span class="hljs-attr">"lastRefTime"</span>: <span class="hljs-number">1528787794594</span>,
	<span class="hljs-attr">"env"</span>: <span class="hljs-string">""</span>,
	<span class="hljs-attr">"clusters"</span>: <span class="hljs-string">""</span>
}
</code></pre>
<h2 id="2.5">Query instance detail</h2>
<h3>Description</h3>
<p>Query instance details of service.</p>
<h3>Request Type</h3>
<p>GET</p>
<h3>Request Path</h3>
<pre><code class="language-plain">/nacos/v1/ns/instance
</code></pre>
<h3>Request Parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Name</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">namespaceId</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>ID of namespace</td>
</tr>
<tr>
<td style="text-align:left">serviceName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>Service name</td>
</tr>
<tr>
<td style="text-align:left">groupName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>group name</td>
</tr>
<tr>
<td style="text-align:left">ephemeral</td>
<td style="text-align:left">boolean</td>
<td style="text-align:left">no</td>
<td>if instance is ephemeral</td>
</tr>
<tr>
<td style="text-align:left">ip</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>IP of instance</td>
</tr>
<tr>
<td style="text-align:left">port</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>Port of instance</td>
</tr>
<tr>
<td style="text-align:left">cluster</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>Cluster name</td>
</tr>
</tbody>
</table>
<h3>Request Example</h3>
<pre><code class="language-plain">curl -X GET '127.0.0.1:8848/nacos/v1/ns/instance?serviceName=nacos.test.2&amp;ip=10.10.10.10&amp;port=8888&amp;cluster=DEFAULT'
</code></pre>
<h3>Response Example</h3>
<pre><code class="language-json">{
	<span class="hljs-attr">"metadata"</span>: {},
	<span class="hljs-attr">"instanceId"</span>: <span class="hljs-string">"10.10.10.10-8888-DEFAULT-nacos.test.2"</span>,
	<span class="hljs-attr">"port"</span>: <span class="hljs-number">8888</span>,
	<span class="hljs-attr">"service"</span>: <span class="hljs-string">"nacos.test.2"</span>,
	<span class="hljs-attr">"healthy"</span>: <span class="hljs-literal">false</span>,
	<span class="hljs-attr">"ip"</span>: <span class="hljs-string">"10.10.10.10"</span>,
	<span class="hljs-attr">"clusterName"</span>: <span class="hljs-string">"DEFAULT"</span>,
	<span class="hljs-attr">"weight"</span>: <span class="hljs-number">1.0</span>
}
</code></pre>
<h2 id="2.6">Send instance beat</h2>
<h3>Description</h3>
<p>Send instance beat</p>
<h3>Request Type</h3>
<p>PUT</p>
<h3>Request Path</h3>
<pre><code class="language-plain">/nacos/v1/ns/instance/beat
</code></pre>
<h3>Request Parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Name</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">namespaceId</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>ID of namespace</td>
</tr>
<tr>
<td style="text-align:left">serviceName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>service name</td>
</tr>
<tr>
<td style="text-align:left">groupName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>group name</td>
</tr>
<tr>
<td style="text-align:left">beat</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>beat content</td>
</tr>
</tbody>
</table>
<h3>Request Example</h3>
<pre><code class="language-plain">curl -X PUT '127.0.0.1:8848/nacos/v1/ns/instance/beat?serviceName=nacos.test.2&amp;beat=%7b%22cluster%22%3a%22c1%22%2c%22ip%22%3a%22127.0.0.1%22%2c%22metadata%22%3a%7b%7d%2c%22port%22%3a8080%2c%22scheduled%22%3atrue%2c%22serviceName%22%3a%22jinhan0Fx4s.173TL.net%22%2c%22weight%22%3a1%7d'
</code></pre>
<h3>Response Example</h3>
<pre><code>ok
</code></pre>
<h2 id="2.7">Create service</h2>
<h3>Description</h3>
<p>Create service</p>
<h3>Request Type</h3>
<p>POST</p>
<h3>Request Path</h3>
<pre><code class="language-plain">/nacos/v1/ns/service
</code></pre>
<h3>Request Parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Name</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">serviceName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>service name</td>
</tr>
<tr>
<td style="text-align:left">groupName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>group name</td>
</tr>
<tr>
<td style="text-align:left">namespaceId</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>namespace id</td>
</tr>
<tr>
<td style="text-align:left">protectThreshold</td>
<td style="text-align:left">float</td>
<td style="text-align:left">no</td>
<td>set value from 0 to 1, default 0</td>
</tr>
<tr>
<td style="text-align:left">metadata</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>metadata of service</td>
</tr>
<tr>
<td style="text-align:left">selector</td>
<td style="text-align:left">JSON</td>
<td style="text-align:left">no</td>
<td>visit strategy</td>
</tr>
</tbody>
</table>
<h3>Request Example</h3>
<pre><code class="language-plain">curl -X POST '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2&amp;metadata=k1%3dv1'
</code></pre>
<h3>Response Example</h3>
<pre><code>ok
</code></pre>
<h2 id="2.8">Delete service</h2>
<h3>Description</h3>
<p>Delete a service, only permitted when instance count is 0.</p>
<h3>Request Type</h3>
<p>DELETE</p>
<h3>Request Path</h3>
<pre><code class="language-plain">/nacos/v1/ns/service
</code></pre>
<h3>Request Parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Name</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">serviceName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>service name</td>
</tr>
<tr>
<td style="text-align:left">groupName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>group name</td>
</tr>
<tr>
<td style="text-align:left">namespaceId</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>namespace id</td>
</tr>
</tbody>
</table>
<h3>Request Example</h3>
<pre><code class="language-plain">curl -X DELETE '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2'
</code></pre>
<h3>Response Example</h3>
<pre><code>ok
</code></pre>
<h2 id="2.9">Update service</h2>
<h3>Description</h3>
<p>Update a service</p>
<h3>Request Type</h3>
<p>PUT</p>
<h3>Request Path</h3>
<pre><code class="language-plain">/nacos/v1/ns/service
</code></pre>
<h3>Request Parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Name</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">serviceName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>service name</td>
</tr>
<tr>
<td style="text-align:left">groupName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>group name</td>
</tr>
<tr>
<td style="text-align:left">namespaceId</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>namespace id</td>
</tr>
<tr>
<td style="text-align:left">protectThreshold</td>
<td style="text-align:left">float</td>
<td style="text-align:left">no</td>
<td>set value from 0 to 1, default 0</td>
</tr>
<tr>
<td style="text-align:left">metadata</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>metadata of service</td>
</tr>
<tr>
<td style="text-align:left">selector</td>
<td style="text-align:left">JSON</td>
<td style="text-align:left">no</td>
<td>visit strategy</td>
</tr>
</tbody>
</table>
<h3>Request Example</h3>
<pre><code class="language-plain">curl -X PUT '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2&amp;metadata=k1%3dv1'
</code></pre>
<h3>Response Example</h3>
<pre><code>ok
</code></pre>
<h2 id="2.10">Query service</h2>
<h3>Description</h3>
<p>Query a service</p>
<h3>Request Type</h3>
<p>GET</p>
<h3>Request Path</h3>
<pre><code class="language-plain">/nacos/v1/ns/service
</code></pre>
<h3>Request Parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Name</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">serviceName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>service name</td>
</tr>
<tr>
<td style="text-align:left">groupName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>group name</td>
</tr>
<tr>
<td style="text-align:left">namespaceId</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>namespace id</td>
</tr>
</tbody>
</table>
<h3>Request Example</h3>
<pre><code class="language-plain">curl -X GET '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2'
</code></pre>
<h3>Response Example</h3>
<pre><code>{
    metadata: { },
    groupName: &quot;DEFAULT_GROUP&quot;,
    namespaceId: &quot;public&quot;,
    name: &quot;nacos.test.2&quot;,
    selector: {
        type: &quot;none&quot;
    },
    protectThreshold: 0,
    clusters: [
        {
            healthChecker: {
                type: &quot;TCP&quot;
            },
            metadata: { },
            name: &quot;c1&quot;
        }
    ]
}
</code></pre>
<h2 id="2.11">Query service list</h2>
<h3>Description</h3>
<p>Query service list</p>
<h3>Request Type</h3>
<p>GET</p>
<h3>Request Path</h3>
<pre><code class="language-plain">/nacos/v1/ns/service/list
</code></pre>
<h3>Request Parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Name</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">pageNo</td>
<td style="text-align:left">int</td>
<td style="text-align:left">yes</td>
<td>current page number</td>
</tr>
<tr>
<td style="text-align:left">pageSize</td>
<td style="text-align:left">int</td>
<td style="text-align:left">yes</td>
<td>page size</td>
</tr>
<tr>
<td style="text-align:left">groupName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>group name</td>
</tr>
<tr>
<td style="text-align:left">namespaceId</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>namespace id</td>
</tr>
</tbody>
</table>
<h3>Request Example</h3>
<pre><code class="language-plain">curl -X GET '127.0.0.1:8848/nacos/v1/ns/service/list?pageNo=1&amp;pageSize=2'
</code></pre>
<h3>Response Example</h3>
<pre><code>{
    &quot;count&quot;:148,
    &quot;doms&quot;: [
        &quot;nacos.test.1&quot;,
        &quot;nacos.test.2&quot;
    ]
}
</code></pre>
<h2 id="2.12">Query system switches</h2>
<h3>Description</h3>
<p>Query system switches</p>
<h3>Request Type</h3>
<p>GET</p>
<h3>Request Path</h3>
<pre><code class="language-plain">/nacos/v1/ns/operator/switches
</code></pre>
<h3>Request Parameters</h3>
<h3>Request Example</h3>
<pre><code class="language-plain">curl -X GET '127.0.0.1:8848/nacos/v1/ns/operator/switches'
</code></pre>
<h3>Response Example</h3>
<pre><code>{
    name: &quot;00-00---000-NACOS_SWITCH_DOMAIN-000---00-00&quot;,
    masters: null,
    adWeightMap: { },
    defaultPushCacheMillis: 10000,
    clientBeatInterval: 5000,
    defaultCacheMillis: 3000,
    distroThreshold: 0.7,
    healthCheckEnabled: true,
    distroEnabled: true,
    enableStandalone: true,
    pushEnabled: true,
    checkTimes: 3,
    httpHealthParams: {
        max: 5000,
        min: 500,
        factor: 0.85
    },
    tcpHealthParams: {
        max: 5000,
        min: 1000,
        factor: 0.75
    },
    mysqlHealthParams: {
        max: 3000,
        min: 2000,
        factor: 0.65
    },
    incrementalList: [ ],
    serverStatusSynchronizationPeriodMillis: 15000,
    serviceStatusSynchronizationPeriodMillis: 5000,
    disableAddIP: false,
    sendBeatOnly: false,
    limitedUrlMap: { },
    distroServerExpiredMillis: 30000,
    pushGoVersion: &quot;0.1.0&quot;,
    pushJavaVersion: &quot;0.1.0&quot;,
    pushPythonVersion: &quot;0.4.3&quot;,
    pushCVersion: &quot;1.0.12&quot;,
    enableAuthentication: false,
    overriddenServerStatus: &quot;UP&quot;,
    defaultInstanceEphemeral: true,
    healthCheckWhiteList: [ ],
    checksum: null
}
</code></pre>
<h2 id="2.13">Update system switch</h2>
<h3>Description</h3>
<p>Update system switch</p>
<h3>Request Type</h3>
<p>PUT</p>
<h3>Request Path</h3>
<pre><code class="language-plain">/nacos/v1/ns/operator/switches
</code></pre>
<h3>Request Parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Name</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">entry</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>switch name</td>
</tr>
<tr>
<td style="text-align:left">value</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>switch value</td>
</tr>
<tr>
<td style="text-align:left">debug</td>
<td style="text-align:left">boolean</td>
<td style="text-align:left">no</td>
<td>if affect the local server, true means yes, false means no, default true</td>
</tr>
</tbody>
</table>
<h3>Request Example</h3>
<pre><code class="language-plain">curl -X PUT '127.0.0.1:8848/nacos/v1/ns/operator/switches?entry=pushEnabled&amp;value=false&amp;debug=true'
</code></pre>
<h3>Response Example</h3>
<pre><code>ok
</code></pre>
<h2 id="2.14">Query system metrics</h2>
<h3>Description</h3>
<p>Query system metrics</p>
<h3>Request Type</h3>
<p>GET</p>
<h3>Request Path</h3>
<pre><code class="language-plain">/nacos/v1/ns/operator/metrics
</code></pre>
<h3>Request Parameters</h3>
<h3>Request Example</h3>
<pre><code class="language-plain">curl -X GET '127.0.0.1:8848/nacos/v1/ns/operator/metrics'
</code></pre>
<h3>Response Example</h3>
<pre><code>{
    serviceCount: 336,
    load: 0.09,
    mem: 0.46210432,
    responsibleServiceCount: 98,
    instanceCount: 4,
    cpu: 0.010242796,
    status: &quot;UP&quot;,
    responsibleInstanceCount: 0
}
</code></pre>
<h2 id="2.15">Query server list</h2>
<h3>Description</h3>
<p>Query server list</p>
<h3>Request Type</h3>
<p>GET</p>
<h3>Request Path</h3>
<pre><code class="language-plain">/nacos/v1/ns/operator/servers
</code></pre>
<h3>Request Parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Name</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">healthy</td>
<td style="text-align:left">boolean</td>
<td style="text-align:left">no</td>
<td>if return healthy servers only</td>
</tr>
</tbody>
</table>
<h3>Request Example</h3>
<pre><code class="language-plain">curl -X GET '127.0.0.1:8848/nacos/v1/ns/operator/servers'
</code></pre>
<h3>Response Example</h3>
<pre><code>{
    servers: [
        {
            ip: &quot;1.1.1.1&quot;,
            servePort: 8848,
            site: &quot;unknown&quot;,
            weight: 1,
            adWeight: 0,
            alive: false,
            lastRefTime: 0,
            lastRefTimeStr: null,
            key: &quot;1.1.1.1:8848&quot;
        },
        {
            ip: &quot;1.1.1.2&quot;,
            servePort: 8848,
            site: &quot;unknown&quot;,
            weight: 1,
            adWeight: 0,
            alive: false,
            lastRefTime: 0,
            lastRefTimeStr: null,
            key: &quot;1.1.1.2:8848&quot;
        },
        {
            ip: &quot;1.1.1.3&quot;,
            servePort: 8848,
            site: &quot;unknown&quot;,
            weight: 1,
            adWeight: 0,
            alive: false,
            lastRefTime: 0,
            lastRefTimeStr: null,
            key: &quot;1.1.1.3:8848&quot;
        }
    ]
}
</code></pre>
<h2 id="2.16">Query the leader of current cluster</h2>
<h3>Description</h3>
<p>Query the leader of current cluster</p>
<h3>Request Type</h3>
<p>GET</p>
<h3>Request Path</h3>
<pre><code class="language-plain">/nacos/v1/ns/raft/leader
</code></pre>
<h3>Request Parameters</h3>
<h3>Request Example</h3>
<pre><code class="language-plain">curl -X GET '127.0.0.1:8848/nacos/v1/ns/raft/leader'
</code></pre>
<h3>Response Example</h3>
<pre><code>{
    leader: &quot;{&quot;heartbeatDueMs&quot;:2500,&quot;ip&quot;:&quot;1.1.1.1:8848&quot;,&quot;leaderDueMs&quot;:12853,&quot;state&quot;:&quot;LEADER&quot;,&quot;term&quot;:54202,&quot;voteFor&quot;:&quot;1.1.1.1:8848&quot;}&quot;
}
</code></pre>
<h2 id="2.17">Update instance health status</h2>
<h3>Description</h3>
<p>Update instance health status, only works when the cluster health checker is set to NONE.</p>
<h3>Request Type</h3>
<p>PUT</p>
<h3>Request Path</h3>
<pre><code class="language-plain">/nacos/v1/ns/health/instance
</code></pre>
<h3>Request Parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Name</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">serviceName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>service name</td>
</tr>
<tr>
<td style="text-align:left">groupName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>group name</td>
</tr>
<tr>
<td style="text-align:left">namespaceId</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>namespace id</td>
</tr>
<tr>
<td style="text-align:left">clusterName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>cluster name</td>
</tr>
<tr>
<td style="text-align:left">ip</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>ip of instance</td>
</tr>
<tr>
<td style="text-align:left">port</td>
<td style="text-align:left">int</td>
<td style="text-align:left">yes</td>
<td>port of instance</td>
</tr>
<tr>
<td style="text-align:left">healthy</td>
<td style="text-align:left">boolean</td>
<td style="text-align:left">yes</td>
<td>if healthy</td>
</tr>
</tbody>
</table>
<h3>Request Example</h3>
<pre><code class="language-plain">curl -X PUT 'http://127.0.0.1:8848/nacos/v1/ns/health/instance?port=8848&amp;healthy=true&amp;ip=11.11.11.11&amp;serviceName=nacos.test.3&amp;namespaceId=n1''
</code></pre>
<h3>Response Example</h3>
<p>ok</p>
<h2 id="2.18">Batch update instance metadata(Beta)</h2>
<h3>Description</h3>
<p>Batch update instance metadata(Since 1.4)</p>
<blockquote>
<p>Note: This API is a Beta API, later versions maybe modify or even delete. Please use it with caution.</p>
</blockquote>
<h3>Request Type</h3>
<p>PUT</p>
<h3>Request Path</h3>
<pre><code class="language-plain">/nacos/v1/ns/instance/metadata/batch
</code></pre>
<h3>Request Parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Name</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">namespaceId</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>ID of namespace</td>
</tr>
<tr>
<td style="text-align:left">serviceName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>Service name(group@@serviceName)</td>
</tr>
<tr>
<td style="text-align:left">consistencyType</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>instance type (ephemeral/persist)</td>
</tr>
<tr>
<td style="text-align:left">instances</td>
<td style="text-align:left">JSON</td>
<td style="text-align:left">no</td>
<td>The instances which need to update</td>
</tr>
<tr>
<td style="text-align:left">metadata</td>
<td style="text-align:left">JSON</td>
<td style="text-align:left">yes</td>
<td>Metadata</td>
</tr>
</tbody>
</table>
<h3>Parameter description</h3>
<ul>
<li>consistencyType: The priority higher than param instances, if config it, the param instances will be ignored. When when value equals 'ephemeral', all the ephemeral instances in serviceName will be updated. When when value equals 'persist', all the persist instances in serviceName will be updated. When other value, no instances will be updated.</li>
<li>instances: json array. To locate particular instances by (ip + port + ephemeral + cluster).</li>
</ul>
<h3>Request Example</h3>
<pre><code class="language-plain">curl -X PUT 'http://localhost:8848/nacos/v1/ns/instance/metadata/batch' -d 'namespaceId=public&amp;serviceName=xxxx@@xxxx&amp;instances=[{&quot;ip&quot;:&quot;3.3.3.3&quot;,&quot;port&quot;: &quot;8080&quot;,&quot;ephemeral&quot;:&quot;true&quot;,&quot;clusterName&quot;:&quot;xxxx-cluster&quot;},{&quot;ip&quot;:&quot;2.2.2.2&quot;,&quot;port&quot;:&quot;8080&quot;,&quot;ephemeral&quot;:&quot;true&quot;,&quot;clusterName&quot;:&quot;xxxx-cluster&quot;}]&amp;metadata={&quot;age&quot;:&quot;20&quot;,&quot;name&quot;:&quot;cocolan&quot;}' 
or
curl -X PUT 'http://localhost:8848/nacos/v1/ns/instance/metadata/batch' -d 'namespaceId=public&amp;serviceName=xxxx@@xxxx&amp;consistencyType=ephemeral&amp;metadata={&quot;age&quot;:&quot;20&quot;,&quot;name&quot;:&quot;cocolan&quot;}'
</code></pre>
<h3>Response Example</h3>
<pre><code>{&quot;updated&quot;:[&quot;2.2.2.2:8080:unknown:xxxx-cluster:ephemeral&quot;,&quot;3.3.3.3:8080:unknown:xxxx-cluster:ephemeral&quot;]}
</code></pre>
<h2 id="2.19">Batch delete instance metadata(Beta)</h2>
<h3>Description</h3>
<p>Batch delete instance metadata(Since 1.4)</p>
<blockquote>
<p>Note: This API is a Beta API, later versions maybe modify or even delete. Please use it with caution.</p>
</blockquote>
<h3>Request Type</h3>
<p>DELETE</p>
<h3>Request Path</h3>
<pre><code class="language-plain">/nacos/v1/ns/instance/metadata/batch
</code></pre>
<h3>Request Parameters</h3>
<table>
<thead>
<tr>
<th style="text-align:left">Name</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">namespaceId</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>ID of namespace</td>
</tr>
<tr>
<td style="text-align:left">serviceName</td>
<td style="text-align:left">String</td>
<td style="text-align:left">yes</td>
<td>Service name(group@@serviceName)</td>
</tr>
<tr>
<td style="text-align:left">consistencyType</td>
<td style="text-align:left">String</td>
<td style="text-align:left">no</td>
<td>instance type (ephemeral/persist)</td>
</tr>
<tr>
<td style="text-align:left">instances</td>
<td style="text-align:left">JSON</td>
<td style="text-align:left">no</td>
<td>The instances which need to update</td>
</tr>
<tr>
<td style="text-align:left">metadata</td>
<td style="text-align:left">JSON</td>
<td style="text-align:left">yes</td>
<td>Metadata</td>
</tr>
</tbody>
</table>
<h3>Parameter description</h3>
<ul>
<li>consistencyType: The priority higher than param instances, if config it, the param instances will be ignored. When when value equals 'ephemeral', all the ephemeral instances in serviceName will be updated. When when value equals 'persist', all the persist instances in serviceName will be updated. When other value, no instances will be updated.</li>
<li>instances: json array. To locate particular instances by (ip + port + ephemeral + cluster).</li>
</ul>
<h3>Request Example</h3>
<pre><code class="language-plain">curl -X DELETE 'http://localhost:8848/nacos/v1/ns/instance/metadata/batch' -d 'namespaceId=public&amp;serviceName=xxxx@@xxxx&amp;instances=[{&quot;ip&quot;:&quot;3.3.3.3&quot;,&quot;port&quot;: &quot;8080&quot;,&quot;ephemeral&quot;:&quot;true&quot;,&quot;clusterName&quot;:&quot;xxxx-cluster&quot;},{&quot;ip&quot;:&quot;2.2.2.2&quot;,&quot;port&quot;:&quot;8080&quot;,&quot;ephemeral&quot;:&quot;true&quot;,&quot;clusterName&quot;:&quot;xxxx-cluster&quot;}]&amp;metadata={&quot;age&quot;:&quot;20&quot;,&quot;name&quot;:&quot;cocolan&quot;}' 
or
curl -X DELETE 'http://localhost:8848/nacos/v1/ns/instance/metadata/batch' -d 'namespaceId=public&amp;serviceName=xxxx@@xxxx&amp;consistencyType=ephemeral&amp;metadata={&quot;age&quot;:&quot;20&quot;,&quot;name&quot;:&quot;cocolan&quot;}'
</code></pre>
<h3>Response Example</h3>
<pre><code>{&quot;updated&quot;:[&quot;2.2.2.2:8080:unknown:xxxx-cluster:ephemeral&quot;,&quot;3.3.3.3:8080:unknown:xxxx-cluster:ephemeral&quot;]}
</code></pre>
</div></div></section><footer class="footer-container"><div class="footer-body"><img src="/img/nacos_gray.png"/><div class="cols-container"><div class="col col-12"><h3>Vision</h3><p>By providing an easy-to-use service infrastructure such as dynamic service discovery, service configuration, service sharing and management and etc., Nacos help users better construct, deliver and manage their own service platform, reuse and composite business service faster and deliver value of business innovation more quickly so as to win market for users in the era of cloud native and in all cloud environments, such as private, mixed, or public clouds.</p></div><div class="col col-6"><dl><dt>Documentation</dt><dd><a href="/en-us/docs/what-is-nacos.html" target="_self">Overview</a></dd><dd><a href="/en-us/docs/quick-start.html" target="_self">Quick start</a></dd><dd><a href="/en-us/docs/contributing.html" target="_self">Developer guide</a></dd></dl></div><div class="col col-6"><dl><dt>Resources</dt><dd><a href="/en-us/community/index.html" target="_self">Community</a></dd><dd><a href="https://www.aliyun.com/product/acm?source_type=nacos_pc_20181219" target="_self">Cloud Service ACM</a></dd><dd><a href="https://www.aliyun.com/product/edas?source_type=nacos_pc_20181219" target="_self">Cloud Service EDAS</a></dd><dd><a href="https://www.aliyun.com/product/ahas?source_type=nacos_pc_20190225" target="_self">Cloud Service AHAS</a></dd></dl></div></div><div class="copyright"><span>@ 2018 The Nacos Authors | An Alibaba Middleware (Aliware) Project</span></div></div></footer></div></div>
	<script src="https://f.alicdn.com/react/15.4.1/react-with-addons.min.js"></script>
	<script src="https://f.alicdn.com/react/15.4.1/react-dom.min.js"></script>
	<script>
		window.rootPath = '';
  </script>
	<script src="/build/documentation.js"></script>
</body>
</html>